Terminal Management

Connect

Connect Method

Configures the device as the preferred device and tries to connect to it. Everytime a new connection is started the SDK will make 3 attempts to re-establish the connection. If those attempts fail, the connection is considered dead.

Parameters

Parameter	Notes
device Required Device	This parameter specifies to the sdk which payment terminal should be used.

Code example

//Connect to a CLOUD device (PAX/Telpo)
Device device = new Device("CloudDevice", "9822032398-PAXA920", "", ConnectionMethod.Cloud);
// The address is the composition of the serial number and model ot the target device.
//Example for a PAX A920 device: serial_number - model  -> 9822032398-PAXA920
api.Connect(device);

//Connect to a BLUETOOTH device (HiLite)
Device device = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH);
api.Connect(device);

Events invoked

ConnectionStatusChanged

Each time the card reader state changes (ex : going from Connected to Disconnected) the ConnectionStatusChanged event is called. It causes the connection manager to invoke this event with the appropriate information.

Returns

Parameter	Notes
Boolean	True if the operation was successful.

Disconnect

Disconnect Method

Disconnect will stop the active connection (and reconnection process). Please note that the method does NOT ignore the current state of the payment terminal. This means that if a disconnect is attempted during a transaction it will not be successful and the method will return false. If a transaction is not in progress, the disconnect will take 1-3 seconds to successfully finish and will then return true.

Parameters

Parameter	Notes
device Required Device	This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.

Code example

//Disconnect from current device
api.Disconnect();

Events invoked

ConnectionStatusChanged

Each time the card reader state changes (ex : going from Connected to Disconnected) the ConnectionStatusChanged event is called. It causes the connection manager to invoke this event with the appropriate information.

Returns

Parameter	Notes
Boolean	True if the operation was succesful

Set shared secret

SetSharedSecret Method

Validates your application for this session, thus enabling financial transactions.

Parameters

Parameter	Notes
sharedSecret Required String	The shared secret is a an authentication key provided by Handpoint, it is unique per merchant (not per terminal).
device Required Device	This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.

Code example

//Sets the shared secret
api.SetSharedSecret("0102030405060708091011121314151617181920212223242526272829303132");

Events invoked

None

No events invoked.

Returns

Parameter	Notes
Boolean	True if the operation was successfully sent to the payment terminal.

Set logging level

SetLogLevel Method

Sets the log level (info, debug etc.) for both the payment terminal and the API.

Parameters

Parameter	Notes
level Required LogLevel	The desired log level. Possible values are LogLevel.None, LogLevel.Info, LogLevel.Full, LogLevel.Debug.
device Required Device	This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.

Code example

//Sets the log level to info
api.SetLogLevel(LogLevel.info);

Events invoked

None

No events are invoked.

Returns

Parameter	Notes
Boolean	True if the operation was successfully sent to the payment terminal.

Request device logs

GetDeviceLogs Method

Fetches the logs from the payment terminal and reports them to the DeviceLogsReady event.

Parameters

Parameter	Notes
device Required Device	This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.

Code example

//Downloads logs from device
api.GetDeviceLogs();

Events invoked

DeviceLogsReady

Invoked when the SDK has finished downloading logs from the payment terminal.

Returns

Parameter	Notes
Boolean	True if the operation was successfully sent to the payment terminal.

Request pending transaction results

GetPendingTransaction Method

In the case of a communication failure between the device and the SDK a TransactionResult might have not been delivered to the API. This function fetches a pending TransactionResult (which contains receipts) from the payment terminal, if any. If no TransactionResult was pending a result will be delivered containing default fields. In order to receive only valid TransactionResults this function should only be called when PendingTransactionResult event is invoked or when HapiManager.IsTransactionResultPending() is true. To receive events when a TransactionResult is pending on the device please add the Events.PendingResults listener.

Parameters

Parameter	Notes
device Required Device	This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.

Code example

//Fetches a pending TransactionResult from a device
api.GetPendingTransaction();

Events invoked

TransactionResultReady

Invoked when the SDK has finished fetching a TransactionResult from the payment terminal.

Returns

Parameter	Notes
Boolean	True if the operation was successfully sent to the payment terminal.

Update device

Update Method

The update operation checks for available software or configuration update. If an update is pending it will be downloaded and installed by the payment terminal.

Parameters

Parameter	Notes
device Required Device	This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.

Code example

//Check for card reader update
api.Update();

Events invoked

None

Information about this process should be available at the device's screen.

Returns

Parameter	Notes
Boolean	True if the operation was successfully sent to the payment terminal.

List Devices (search)

ListDevices Method

Starts the search for payment terminals to connect to.

Parameters

Parameter	Notes
method Required ConnectionMethod	The connection type to the payment terminal (Bluetooth or Cloud)

Code example

//Search for Bluetooth devices
api.ListDevices(ConnectionMethod.BLUETOOTH);

//Search for Cloud devices
api.ListDevices(ConnectionMethod.CLOUD);

Events invoked

deviceDiscoveryFinished

Returns a list of available payment terminals.

Start monitoring connections

StartMonitoringConnections Method

Starts a connection monitoring service. The service listens to events sent by the operating system about the connected hardware. If the service notices that a previously connected device suddenly disconnects on the hardware layer it attempts to reconnect to that particular device. Since this is a service it is necessary that the service is turned off before the application ends its life-time. This means that, if the service was running, stopMonitoringConnections() has to be called before the application is exited completely. Note that the service currently only works with USB. In the case of USB the service will only disconnect from the device and when it notices that it has been plugged in again it will connect to it.

Code example

//Starts the connection monitoring service
//app starts it's life-time
api.StartMonitoringConnections();
...
//app ends its life-time
api.StopMonitoringConnections();

Events invoked

ConnectionStatusChanged

Invoked when the status of the connection with the payment terminal changes.

Returns

Parameter	Notes
None	No information is returned.

Stop monitoring connections

StopMonitoringConnections Method

Stops a connection monitoring service. The service listens to events sent by the operating system about the connected hardware. If the service notices that a previously connected device suddenly disconnects on the hardware layer it attempts to reconnect to that particular device. Since this is a service it is necessary that the service is turned off before the application ends its life-time. This means that, if the service was running, stopMonitoringConnections() has to be called before the application is exited completely. Note that the service currently only works with USB. In the case of USB the service will only disconnect from the device and when it notices that it has been plugged in again it will connect to it.

Code example

//Starts the connection monitoring service
//app starts it's life-time
api.StartMonitoringConnections();
...
//app ends its life-time
api.StopMonitoringConnections();

Events invoked

ConnectionStatusChanged

Invoked when the status of the connection with the payment terminal changes.

Returns

Parameter	Notes
None	No information is returned.